nvx-rs: make the rustdoc and module diagrams describe the final public API (SL6.10g) - #1562

Part of #1131 (SL6.10g, "The rustdoc agrees with the final public API"). Parent #1090, umbrella #1076.

What and why

After every code slice of #1076 merged, the rustdoc of nvx and the module diagrams still described the crate before the slimming: the crate root introduced "NVX mechanics" for the "launch, policy lowering, and supervision" of NVX's sandboxes run by a managed agent; host's and guest's overviews listed NVX's private program code (the CLI's artifacts, policy files, export planner, NVXC session, restore driver and sandbox profile; nvx-init's space, the guest programs and their conventions) beside the library; several item docs named removed mechanisms as current; and doc/modules/ still drew host::{instance, launch, store, supervisor, template}, guest::{exec, spawn, process, cgroup, entry}, the guest's space, NVXC and the CLI. The generator could no longer even draw the crate: SL6.5a2 put host::platform::linux::identity under cfg(any(test, feature = "cli")), which restore() refused.

This PR makes the public rustdoc and the diagrams describe the final public API, as the Scope of SL6.10g says, with doc comments only on the Rust side (no code changes, and the public-API snapshots don't change):

• Crate and module overviews (lib.rs, host, guest, protocol): the final public modules, Error and ErrorKind included; what the library does not do (it keeps no state, starts OpenVMM and no other process on the host, supervises no VM, takes no lock that its caller sees); what the caller owns, linking the library guide's What the caller owns from doc: describe only the final nvx library in a guide and the READMEs (SL6.10a) #1555 and the guest-agent guidelines; and one paragraph saying that NVX's own programs live in the crate, private, behind hidden entry points. The overviews no longer list private program code. The guest programs' compatibility rules and the guest module's coding conventions move, verbatim, to the private guest::status module that the programs share.
• NVX's programs out of the public narrative: guest::activation no longer describes nvx-init's application of a record (the text moves, verbatim, to the private guest::activation::state::apply that implements it, whose docs pointed back to the public ones) and points to the guidelines' Build the space; guest::mappings, MappingTable and protocol::maps say that the caller mounts with a mapper of its own, and name the public MappingTable rather than the managed agent as what refuses an empty source; protocol::cmdline names VmConfig::check rather than the CLI's sandbox check; host::network and ExportPlan::check no longer refer to the CLI's private policy files, planner and plan function.
• No removed module as current API: contract no longer says that "the store" records a VM's versions (the caller saves its RuntimeIdentity), nor that the control contract carries the agent's "features" (NVXC v1's FEATURES); ArtifactIdentity is compared by the library, not "the store"; ErrorKind::NotFound's example is a missing capture manifest, not a sandbox store; SnapshotKey speaks of the runtime, not a "bundle", and no longer "recertifies" templates; CaptureStage::Fence says that no capture has that stage any more (the variant stays, for the API's sake); guest::time names TIME_ABI_VERSION instead of "time ABI v2", which OpenVMM's v4 microVM restarted at 1; Hypervisor and BlockGeometry describe any VM's, not a sandbox's.
• Intra-doc links: VmmCommand's spawn link names the function (it was ambiguous with the private host::spawn module once private items are documented), the Windows log claim's docs link spawn_with_stdio instead of the deleted spawn_detached, and two redundant explicit links of guest::root go, so that cargo doc --document-private-items passes with warnings denied on both platforms.
• launch::direct_request said that the workload's standard input is the null device. The request that it builds does read the null device, which its unit test checks, but its only caller replaces it with a pipe for every workload since SL4.4c, so the docs described what no workload gets. They now say both.
• Module diagrams: scripts/module_diagrams.py draws the crate's public API: public() keeps, in each platform's export before the platforms merge, each module that is public, as are the modules that contain it, but the modules of NVX's programs, which a fixed list, PROGRAMS, names (the CLI, the fake OpenVMM and the eight guest programs: the modules that the public-API snapshots mark (hidden)), and the uses that involve a module that it leaves out; a module that is public on one platform alone is drawn as that platform's. DESCRIPTIONS, the fixed inventory of top-level modules, describes the eight public ones; the test doubles' color goes. restore() accepts any(test, feature = "F") for a feature that the export enables. The page says what the diagrams cover, and that CI draws them every night (the workflow moved to a nightly run in 77bb5e7, but the page still said "after every merge"). doc/ci.md's Module diagrams section follows, and doc/project-structure.md's two mentions of the workflow, which said that it draws the diagrams "after merges", say "every night" (SL6.10e, doc: describe the nvx package's build, release packages and setup (SL6.10e) #1546, which owns that file, merged first). The export, features and targets, the merge, the layout and .github/workflows/module-diagrams.yml don't change, so the nightly run keeps publishing the set.
• doc/modules/, regenerated by the script (not by hand) with the workflow's tools: overview, dependencies, and the hierarchies of guest, host, net and protocol; activation, gpt and testing contain no public module, so their diagrams go.
• Case matrix: the doc tests whose lines moved keep their rows under their new names: lib.rs - (line 67) (coverage named by two rows), guest::activation (line 127), MappingTable (line 46), guest::time (line 10). Counts unchanged.

Decisions

1. The diagrams' scope is the public API, crisp rather than judged: a module is drawn when it and every module that contains it are pub, and it is no program's. The alternative, drawing private library modules dashed but leaving out "program code", needs a judgment for each private module (the OS layers, NVXC, the CLI's sandbox profile, nvx-init's space…) and would still draw the guest's space that SL6.13b made private. PROGRAMS is a fixed list, as the Approach asks ("adjust the generator's fixed public-module inventory … do not introduce discovery"); a program module that a later PR adds shows as public until someone lists it, and its (hidden) line in the public-API snapshot diff is the cue.
2. The export keeps the cli, testing and guest features, as docs.rs and the public-API snapshots document the crate, so the drawn modules are exactly the snapshots' non-hidden ones (37 on Linux); doc/ci.md's description of the export stays true.
3. The diagrams were drawn with CI's tools on a Linux host, not on Windows: cargo-modules 0.27.0 built with Rust 1.95.0 on nvx-kvm-test, and Graphviz from Ubuntu 24.04 (graphviz 2.42.2-9ubuntu0.1, dot 2.43.0) with fonts-liberation 1:2.1.5-3 in an ubuntu:24.04 container, so that dev's nightly run, on ubuntu-24.04, finds the same files once this branch reaches dev.
4. Private docs move rather than go: the guest programs' compatibility rules and conventions, and nvx-init's application, leave the public docs but stay with the private code that they describe.
5. The scope applies to each platform before the merge, as Copilot's review asked: merge() writes the visibility of a module that differs between platforms as pub on Linux, pub(crate) on Windows, so a filter of the merged crate would lose a module that is public on one platform alone, with its public descendants. No module of the crate has such a visibility today, so the drawn diagrams are the same either way.
6. "Clone" and "template" stay where they name a VM that a restore starts and the VM whose capture makes a snapshot: the final design docs, the README and the library's own error messages use them. Only the sentences that tied them to the removed template store change.

Tests

python3 scripts/check_test_changes.py --base origin/feature/nvx-refactor lists 4 changed tests, all in scripts/test_module_diagrams.py, and 4 additions:

• DrawTests.test_draw_exports_each_platform_and_writes_the_page_and_diagrams expects the diagrams of the merge of each platform's public() export, which draw() now draws; the equality of what it drew with them is what checks that draw() applies the scope.
• DrawTests.test_draw_restores_the_modules_that_cargo_modules_drops_as_tests makes its restored nvx::host::imp public on both platforms, so that the hierarchy that it inspects still draws it; it still checks that the module returns and the test module does not.
• GraphTests.test_the_overview_shows_every_top_level_module_in_the_crate expects no description of the private error, which DESCRIPTIONS no longer holds.
• PageTests.test_the_page_leads_to_how_ci_draws_the_diagrams expects "CI draws them again every night".
• Added: the class PublicTests, with test_the_public_api_leaves_out_private_modules_and_programs (a program, a public module inside it or inside a private module, and the uses that involve them go; public modules and their uses stay) and test_a_module_public_on_one_platform_alone_is_that_platform_s (a module that is pub on Linux and pub(crate) on Windows is drawn, marked Linux's, with its public descendant), and RestoreTests.test_a_test_or_a_feature_that_the_export_enables_builds_outside_tests (any(test, feature = "cli") restores; any(test, feature = "other") still fails). All three fail without the change.

No test is removed. The doc tests are unchanged apart from the lines of the four that move (see the case matrix above).

Size

• Core lines: 57, in 1 counted file, scripts/module_diagrams.py: public() and its call (20), PROGRAMS (14), the restore() exception (4), DESCRIPTIONS (4), and the page's and the dependency diagram's text (15). This passes SL6.10g's estimate of 0 core lines and no counted files, whose stop is therefore 0: the Scope's "update scripts/module_diagrams.py … for the final diagram scope" needs code, and the generator failed on the final package. The size is accepted, and the script stays in this pull request: see the decision on #1131.
• The Rust changes are doc comments only (24 files, 0 core lines). The test file, the docs, the case matrix and the generated diagrams don't count.

Commits

1. nvx-rs: describe the final library and what its caller owns
2. nvx-rs: leave NVX's programs out of the public rustdoc
3. nvx-rs: name no removed store, bundle or fence in the rustdoc
4. nvx-rs: fix the intra-doc links that private items break
5. guest: say that the managed agent's workloads read a pipe
6. scripts: restore the modules under a test or an enabled feature
7. scripts: draw the public modules of nvx in the module diagrams
8. doc: draw the module diagrams of the final public API

Not in this PR

New public APIs, module moves or compatibility aliases (guest::clone and host::nvxs stay); a new generator, renderer or site; hand edits of doc/modules; the prose guides of SL6.10a–SL6.10f, but for the two mentions of the diagrams' workflow in doc/project-structure.md; renaming "clone" or "template" in the rustdoc; the crate root's links to host, which break in --no-default-features doc builds as before this PR (CI documents with every feature).

Validation

Final rebase. The head, 25cd1567, is 76c51d83 rebased onto 7e5440a1, after SL6.10c, SL6.10b, SL6.10a and SL6.10d, which changed docs only; git range-diff shows every commit unchanged, and rebase_check.py verify passed. The rustdoc's links into the guides, doc/library.md#what-the-caller-owns and doc/guest-agent-guidelines.md#build-the-space, name headings that the final guides hold. At 25cd1567:

• RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps --all-features passed on Windows, for x86_64-unknown-linux-musl, and on Linux, where --features guest passed too.
• cargo test --locked --all-features --doc passed: 6 on Windows, 15 on Linux.
• python scripts/public_api.py passed, and the snapshots are unchanged.
• check_markdown_links.py, check_test_layout.py and SL5.2's check_matrix.py passed; check_test_changes.py lists the same 4 changed and 4 added tests.
• validate-nvx's Windows step passed: 1806 tests OK, 73 skipped; test_adversarial.py 84 OK, 11 skipped; test_hosts.py 4 OK; the six nvx.py … --help exit 0.
• Two draws of module_diagrams.py on nvx-kvm-test equal each other and the committed doc/modules, so no diagram changed.
• CI run 43354639966 passed: 33 jobs succeeded, among them nvx-rs on both platforms, the NVX CLI on both, and the microVM tests on KVM, MSHV and WHP; 9 skipped, the publishing and recording jobs among them.

The rest of this section is the validation of 76c51d83, which was rebased onto e6c65b95, after SL6.10f (#1540) and SL6.10e (#1546), whose docs, instructions and setup READMEs it brought. Its nvx-rs/ is the one that the Rust checks below ran on (git diff 794f9343344 HEAD -- nvx-rs is empty: after them, only the scripts' per-platform filter, its tests and the docs changed); the rows marked "(head)" ran at 76c51d83. The gates are those that dev's local_gates.py (from the orchestration checkout) selects from this branch's own action definitions, once the four check-nvx-rs steps that the feature branch no longer has leave its table: on Windows, test-changes, markdown-links, test-layout, quality-code, nvx-rs-format, nvx-rs-lint, nvx-rs-test, nvx-rs-doc, nvx-rs-msrv and nvx-cli; on Linux, also nvx-rs-public-api, nvx-rs-macos, and the guest binaries' lint and build.

Windows (x86_64-pc-windows-msvc), Rust 1.95.0:

Linux, nvx-kvm-test (Azure Linux 3, kernel 6.6.159.1-1.azl3), Rust 1.95.0, at b79fce15 (the same nvx-rs/) unless noted:

Code review: a code-review subagent reviewed the whole diff; its one finding, doc/project-structure.md's "drawn after merges", is fixed now that SL6.10e (#1546), which owns that file, has merged. Copilot's review left one thread, on the merged visibility that public() filtered; public() now filters each platform's export (Decision 5), and the thread is answered and resolved.

Left to CI: on Linux, check-nvx-rs's cargo test (its doc tests ran above; the Rust changes are doc comments), the macOS check, and the guest binaries' build and test; the microVM suites (nothing at run time changes); and module-diagrams.yml, which runs only for pull requests into dev and for dev itself.